This piece of software was created using Free Pascal (FPC) and Lazarus.
For details about the Free Pascal license see "COPYING.FPC".



This is a project for providing a library to perform HTTP requests.
It contains the Lazarus Project and the complied .DLL (Windows 32-bit).
It uses the following units:
- sysutils ... is necessary for Exception handling.
- classes ... is used for the TStringStream and TStrings and possibly other classes.
- fphttpclient ... provides the TFPHttpClient class which is used to send the requests.
- base64 ... is needed for the EncodeStringBase64 function.
- fpjson and jsonparser ... are used to process the the request headres.

It has been implemented with performing calls from ADOxx in mind.
As such the AdoScript file "ASC_HttpRequestDll.asc" containing several procedures is provided as well.
See that file for additional details about its setup and the provided procedures.



If you simply want to use it in ADOxx:
* Copy the "HttpRequestDll.dll" into the ADOxx installation directory (something like "C:\Program Files (x86)\BOC\ADOxx151UL5_EN_SA\").
* Load the code from "ASC_HttpRequestDll.asc" into the ADOxx library where you want to perform the HTTP calls.
  The best way to achieve this is to add the .asc file through the ADOxx Development Toolkit File Management to library and then load it when the tool is initialized through the library attribute "External coupling".
  EXECUTE file:("db:\\ASC_HttpRequestDll.asc")

NOTE: If the "HttpRequestDll.dll" is not present in the ADOxx installation folder, but at a different place then change the global variable "global_str_dll_httprequest" in "ASC_HttpRequestDll.asc" to the location of that file including the filename of the DLL itself.



The DLL itself provides 20 functions using C type calling convention.
12 of those functions allow to make HTTP requests and return the provided response.
The functions differ in three aspects:
- Decoding of the provided request body (as is, base64 decode). See "reqbody" parameter below for more details.
- Encoding of the returned response body (plain string, base64 encoded, list of bytes). See "(out) respbody" parameter below for more details.
- If authentication is used (user name + password).
8 of those functions provide support when dealing with HTTP requests/responses.
Currently they help with the following tasks:
- (4*) Percent-Encoding special characters of a text/string, as for a URL's query/parameters.
- (4*) Transforming and Percent-Encoding a simple JSON object, with keys and values as strings, into the format used by content-type 'application/x-www-form-urlencoded' and the query/parameter part of a URL.



### Http Call - Details:
All functions use the following parameters, all of which are strings/PChar:
- method ... specifies which HTTP method should be used (e.g. GET, POST, DELETE, HEAD etc.). Whether it works or not depends on the contacted server.
- address ... specifies where the request should be sent.
- reqheaders ... a JSON object as a string with the desired header values. Keys and values should be of type string. "Host" and "Content-Length" seem to always be present automatically, but others like "Accept", "Content-Type" or "Authorization" have to be specified manually.
- reqbody ... the body of the request as a string. The content provided will be either sent "as-is" or decoded using bae64 before sending it. The base64 option is provided if data containing NUL bytes has to be sent (e.g. PUT request sending a .png image). Which one is used depends on the called function. Functions performing the base64 decoding have a name ending with "In64" while the ones without decoding don't.
- (out) respheaders ... a JSON object as a string that will have the headers from the response. Keys and values are of type string.
- (out) respbody ... will contain the body of the response. It's encoding depends on the used function. HRHttpCall returns the string fromt the response as is. HRHttpCallBase64 returns the string from the response encoded in base64. HRHttpCallBytes transforms the string from the response into a comma separated list of bytes (in the decimal number system) and returns that. Of course there are also HRHttpCallIn64, HRHttpCallBase64In64 and HRHttpCallBytesIn64.
The return value for each function is a 32-bit int with the HTTP Status code from the server response or 0 if something failed before the request could be made/response was received.
Additionally some of the functions provide parameters for authentication (HRAuthHttpCall, HRAuthHttpCallBase64, HRAuthHttpCallBytes), which are again strings/Pchar:
- uname ... the user name to be used for authentication.
- upw ... the password to be used for authentication.
The functions don't do any fancy translation of "HTTP parameters" (e.g. from a form). The programmer using this library has to take care of this themselves. This is because the style of those parameters depends on a) the used method (GET vs. POST) and b) the used Content-Type. However, there are some utility functions provided to support the programmer.

A bit of help to decide which function to use:
- If you want to send a simple string request and receive a simple string response then use "HRHttpCall", for example when sending/receiving data as XML or JSON or uploading simple text files.
- If you want to send a simple request and expect the response to contain NUL bytes (e.g. as can be for images) then use "HRHttpCallBase64" or "HRHttpCallBytes", whichever is easier for you to process/kdecode.
- If you want to send content containing NUL bytes with a request, but the actual content sent to the server should not be encoded then first encode the content in base64 and use one of the functions ending with "In64".
- If you want to use basic authentication then use the version with "Auth" in the function's name.

Function signatures:
- HRHttpCall(method, address, reqheaders, reqbody : PChar; out respheaders, respbody : PChar) : longint
- HRAuthHttpCall(method, address, uname, upw, reqheaders, reqbody : PChar; out respheaders, respbody : PChar) : longint
- HRHttpCallBase64(method, address, reqheaders, reqbody : PChar; out respheaders, respbody : PChar) : longint
- HRAuthHttpCallBase64(method, address, uname, upw, reqheaders, reqbody : PChar; out respheaders, respbody : PChar) : longint
- HRHttpCallBytes(method, address, reqheaders, reqbody : PChar; out respheaders, respbody : PChar) : longint
- HRAuthHttpCallBytes(method, address, uname, upw, reqheaders, reqbody : PChar; out respheaders, respbody : PChar) : longint
- HRHttpCallIn64(method, address, reqheaders, reqbody : PChar; out respheaders, respbody : PChar) : longint
- HRAuthHttpCallIn64(method, address, uname, upw, reqheaders, reqbody : PChar; out respheaders, respbody : PChar) : longint
- HRHttpCallBase64In64(method, address, reqheaders, reqbody : PChar; out respheaders, respbody : PChar) : longint
- HRAuthHttpCallBase64In64(method, address, uname, upw, reqheaders, reqbody : PChar; out respheaders, respbody : PChar) : longint
- HRHttpCallBytesIn64(method, address, reqheaders, reqbody : PChar; out respheaders, respbody : PChar) : longint
- HRAuthHttpCallBytesIn64(method, address, uname, upw, reqheaders, reqbody : PChar; out respheaders, respbody : PChar) : longint



### Http Utility - Details:
* Percent-Encoding:
All of the functions use one string/PChar parameter:
- text ... the text/string whose special ("not allowed") characters are Percent-Encoded.
They also all return one string/PChar value, which contains the input only where "not allowed" characters are Percent-Encoded (%xx, where xx are two hexadecimal digits).
Depending on which function is used more strict or lax sets of characters are allowed, with JS being the strictest and VeryLax being the most lenient:
- JS ... The list of characters which aren't encoded is based on the Java Script encodeURIComponent() function, which is mostly alpha numeric and a few simple punctuations !'()*-._~
- Inter ... The list of characters which aren't encoded is based on several sources from the Internet, including the URI specification.
- Lax ... Encodes all non-ASCII characters, ASCII control characters (0x00 to 0x20 and 0x7F), # (0x23), % (0x25), & (0x26), + (0x2B), = (0x3D) and ? (0x3F)
- VeryLax ... Encodes all non-ASCII characters, ASCII control characters (0x00 to 0x20 and 0x7F), % (0x25), & (0x26) and = (0x3D)

Function signatures:
- HRUrlEncodeJS(const text : PChar) : PChar;
- HRUrlEncodeInter(const text : PChar) : PChar;
- HRUrlEncodeLax(const text : PChar) : PChar;
- HRUrlEncodeVeryLax(const text : PChar) : PChar;


* JSON to 'application/x-www-form-urlencoded' transformation:
All of the functions use one string/PChar parameter:
- paramsjson ... a string containing the JSON object to be transformed. Both the keys and the values must be of type string.
They also all return one string/PChar value, which is the transformed input with the special characters escaped using Percent-Encoding. As an example the following JSON object is transformed to the string in the next line:
{"param1": "value1", "param2": "value2", "param3": "value3"}
param1=value1&param2=value2&param3=value3
There are again different functions available to handle the encoding of special/"not allowed" characters. Internally they use the functions for Percent-Encoding, so the same "not/ allowed" characters apply as above.

Function signatures:
- HRUrlEncodeQueryJS(const paramsjson : PChar) : PChar
- HRUrlEncodeQueryInter(const paramsjson : PChar) : PChar
- HRUrlEncodeQueryLax(const paramsjson : PChar) : PChar
- HRUrlEncodeQueryVeryLax(const paramsjson : PChar) : PChar